/**
 * @file mqtt_client.h
 * @brief MQTT客户端接口 - IoT平台通信模块
 * @details 提供MQTT协议的订阅、发布等基础功能，用于与IoT平台通信
 * 
 * @author zyb
 * @date 2025-10-30
 * @version 1.0
 */

#ifndef IOT_MQTT_CLIENT_H
#define IOT_MQTT_CLIENT_H

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 错误码定义 ==================== */

/**
 * @brief MQTT操作结果类型
 */
typedef enum {
    MQTT_SUCCESS = 0,                   /* 操作成功 */
    MQTT_ERROR_INVALID_PARAM = -1,      /* 无效参数 */
    MQTT_ERROR_CONNECT_FAILED = -2,     /* 连接失败 */
    MQTT_ERROR_DISCONNECT_FAILED = -3,  /* 断开失败 */
    MQTT_ERROR_PUBLISH_FAILED = -4,     /* 发布失败 */
    MQTT_ERROR_SUBSCRIBE_FAILED = -5,   /* 订阅失败 */
    MQTT_ERROR_TIMEOUT = -6,            /* 超时 */
    MQTT_ERROR_NOT_CONNECTED = -7,      /* 未连接 */
    MQTT_ERROR_MEMORY = -8,             /* 内存错误 */
    MQTT_ERROR_UNKNOWN = -9             /* 未知错误 */
} mqtt_result_t;

/**
 * @brief MQTT连接状态
 */
typedef enum {
    MQTT_STATUS_DISCONNECTED = 0,       /* 未连接 */
    MQTT_STATUS_CONNECTING,             /* 连接中 */
    MQTT_STATUS_CONNECTED,              /* 已连接 */
    MQTT_STATUS_DISCONNECTING,          /* 断开中 */
    MQTT_STATUS_ERROR                   /* 错误状态 */
} mqtt_status_t;

/**
 * @brief MQTT QoS级别
 */
typedef enum {
    MQTT_QOS_0 = 0,                     /* 最多一次 */
    MQTT_QOS_1 = 1,                     /* 至少一次 */
    MQTT_QOS_2 = 2                      /* 只有一次 */
} mqtt_qos_t;

/* ==================== 数据结构定义 ==================== */

/**
 * @brief MQTT客户端配置
 */
typedef struct {
    char broker[256];                   /* Broker地址 */
    uint16_t port;                      /* 端口号 */
    char client_id[64];                 /* 客户端ID */
    char username[64];                  /* 用户名 */
    char password[128];                 /* 密码 */
    uint16_t keepalive;                 /* 保持连接时间(秒) */
    mqtt_qos_t qos;                     /* 默认QoS级别 */
    bool clean_session;                 /* 清除会话 */
    bool use_tls;                       /* 使用TLS/SSL */
} mqtt_config_t;

/**
 * @brief MQTT消息结构
 */
typedef struct {
    char topic[256];                    /* 主题 */
    uint8_t* payload;                   /* 消息内容 */
    size_t payload_len;                 /* 消息长度 */
    mqtt_qos_t qos;                     /* QoS级别 */
    bool retained;                      /* 保留消息标志 */
} mqtt_message_t;

/**
 * @brief MQTT统计信息
 */
typedef struct {
    uint64_t messages_published;        /* 发布消息数 */
    uint64_t messages_received;         /* 接收消息数 */
    uint64_t bytes_sent;                /* 发送字节数 */
    uint64_t bytes_received;            /* 接收字节数 */
    uint64_t connection_count;          /* 连接次数 */
    uint64_t error_count;               /* 错误次数 */
} mqtt_stats_t;

/* ==================== 回调函数类型 ==================== */

/**
 * @brief MQTT消息接收回调函数
 * @param topic 主题
 * @param payload 消息内容
 * @param payload_len 消息长度
 * @param user_data 用户数据
 */
typedef void (*mqtt_message_callback_t)(const char* topic, 
                                        const uint8_t* payload, 
                                        size_t payload_len, 
                                        void* user_data);

/**
 * @brief MQTT连接状态回调函数
 * @param status 连接状态
 * @param user_data 用户数据
 */
typedef void (*mqtt_status_callback_t)(mqtt_status_t status, void* user_data);

/**
 * @brief MQTT错误回调函数
 * @param error 错误码
 * @param user_data 用户数据
 */
typedef void (*mqtt_error_callback_t)(mqtt_result_t error, void* user_data);

/* ==================== MQTT客户端句柄 ==================== */

/**
 * @brief MQTT客户端句柄
 */
typedef struct mqtt_client* mqtt_client_handle_t;

/* ==================== 函数声明 ==================== */

/**
 * @brief 初始化MQTT模块
 * @details 初始化MQTT客户端模块
 * 
 * @return 初始化结果
 */
mqtt_result_t mqtt_init(void);

/**
 * @brief 清理MQTT模块
 * @details 清理MQTT客户端模块资源
 * 
 * @return 清理结果
 */
mqtt_result_t mqtt_cleanup(void);

/**
 * @brief 创建MQTT客户端
 * @details 创建MQTT客户端实例
 * 
 * @param config MQTT配置参数
 * @return MQTT客户端句柄，失败返回NULL
 */
mqtt_client_handle_t mqtt_client_create(const mqtt_config_t* config);

/**
 * @brief 销毁MQTT客户端
 * @details 销毁MQTT客户端实例，释放资源
 * 
 * @param client MQTT客户端句柄
 * @return 销毁结果
 */
mqtt_result_t mqtt_client_destroy(mqtt_client_handle_t client);

/**
 * @brief 连接到MQTT Broker
 * @details 建立与MQTT Broker的连接
 * 
 * @param client MQTT客户端句柄
 * @return 连接结果
 */
mqtt_result_t mqtt_client_connect(mqtt_client_handle_t client);

/**
 * @brief 断开MQTT连接
 * @details 断开与MQTT Broker的连接
 * 
 * @param client MQTT客户端句柄
 * @return 断开结果
 */
mqtt_result_t mqtt_client_disconnect(mqtt_client_handle_t client);

/**
 * @brief 订阅主题
 * @details 订阅指定的MQTT主题
 * 
 * @param client MQTT客户端句柄
 * @param topic 主题名称
 * @param qos QoS级别
 * @return 订阅结果
 */
mqtt_result_t mqtt_client_subscribe(mqtt_client_handle_t client, 
                                    const char* topic, 
                                    mqtt_qos_t qos);

/**
 * @brief 取消订阅主题
 * @details 取消订阅指定的MQTT主题
 * 
 * @param client MQTT客户端句柄
 * @param topic 主题名称
 * @return 取消订阅结果
 */
mqtt_result_t mqtt_client_unsubscribe(mqtt_client_handle_t client, 
                                      const char* topic);

/**
 * @brief 发布消息
 * @details 向指定主题发布MQTT消息
 * 
 * @param client MQTT客户端句柄
 * @param topic 主题名称
 * @param payload 消息内容
 * @param payload_len 消息长度
 * @param qos QoS级别
 * @param retained 是否保留消息
 * @return 发布结果
 */
mqtt_result_t mqtt_client_publish(mqtt_client_handle_t client,
                                  const char* topic,
                                  const uint8_t* payload,
                                  size_t payload_len,
                                  mqtt_qos_t qos,
                                  bool retained);

/**
 * @brief 获取连接状态
 * @details 获取MQTT客户端当前连接状态
 * 
 * @param client MQTT客户端句柄
 * @return 连接状态
 */
mqtt_status_t mqtt_client_get_status(mqtt_client_handle_t client);

/**
 * @brief 设置消息回调
 * @details 设置接收消息的回调函数
 * 
 * @param client MQTT客户端句柄
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return 设置结果
 */
mqtt_result_t mqtt_client_set_message_callback(mqtt_client_handle_t client,
                                               mqtt_message_callback_t callback,
                                               void* user_data);

/**
 * @brief 设置状态回调
 * @details 设置连接状态变化的回调函数
 * 
 * @param client MQTT客户端句柄
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return 设置结果
 */
mqtt_result_t mqtt_client_set_status_callback(mqtt_client_handle_t client,
                                              mqtt_status_callback_t callback,
                                              void* user_data);

/**
 * @brief 设置错误回调
 * @details 设置错误事件的回调函数
 * 
 * @param client MQTT客户端句柄
 * @param callback 回调函数
 * @param user_data 用户数据
 * @return 设置结果
 */
mqtt_result_t mqtt_client_set_error_callback(mqtt_client_handle_t client,
                                             mqtt_error_callback_t callback,
                                             void* user_data);

/**
 * @brief 获取统计信息
 * @details 获取MQTT客户端统计信息
 * 
 * @param client MQTT客户端句柄
 * @param stats 统计信息输出
 * @return 获取结果
 */
mqtt_result_t mqtt_client_get_stats(mqtt_client_handle_t client, 
                                    mqtt_stats_t* stats);

/**
 * @brief 重置统计信息
 * @details 重置MQTT客户端统计信息
 * 
 * @param client MQTT客户端句柄
 * @return 重置结果
 */
mqtt_result_t mqtt_client_reset_stats(mqtt_client_handle_t client);

/**
 * @brief 检查连接状态
 * @details 检查MQTT客户端是否已连接
 * 
 * @param client MQTT客户端句柄
 * @return 是否已连接
 */
bool mqtt_client_is_connected(mqtt_client_handle_t client);

#ifdef __cplusplus
}
#endif

#endif /* IOT_MQTT_CLIENT_H */

